home *** CD-ROM | disk | FTP | other *** search
/ AppleScript - The Beta Release / AppleScript - The Beta Release.iso / Documentation / develop / Better Apple Event Coding / Code Samples / AEObjects.h next >
Encoding:
C/C++ Source or Header  |  1992-10-16  |  9.9 KB  |  259 lines  |  [TEXT/MPS ]
  1. /*———————————————————————————————————————————————————————————————————————————————————*/
  2. /*                                            
  3.     ©Apple Computer, Inc.  2/21/91             
  4.           All Rights Reserved.                
  5.  
  6. */
  7.  
  8. #ifndef __AEOBJECTS__
  9. #define __AEOBJECTS__
  10.  
  11. #ifndef __MEMORY__
  12. #include <Memory.h>
  13. #endif
  14.  
  15.  
  16. #ifndef __OSUTILS__
  17. #include <OSUtils.h>
  18. #endif
  19.  
  20. #ifndef __EVENTS__
  21. #include <Events.h>
  22. #endif
  23.  
  24. #ifndef __EPPC__
  25. #include <EPPC.h>
  26. #endif
  27.  
  28. #ifndef __APPLEEVENTS__
  29. #include <AppleEvents.h>
  30. #endif
  31.  
  32.  
  33.  
  34. /* Logical operators: look for them in descriptors of type typeLogicalDescriptor
  35.   with keyword keyAELogicalOperator */
  36. #define kAEAND                        'AND '
  37. #define kAEOR                        'OR  '
  38. #define kAENOT                        'NOT '
  39.  
  40. /* Absolute ordinals: look for them in descriptors of type typeAbsoluteOrdinal.
  41.   Possible use is as keyAEKeyData in an object specifier whose keyAEKeyForm
  42.   field is formAbsolutePosition. */
  43. #define kAEFirst                    'firs'
  44. #define kAELast                        'last'
  45. #define kAEMiddle                    'midd'
  46. #define kAEAny                        'any '
  47. #define kAEAll                        'all '
  48.  
  49. /*  Relative ordinals: look for them in descriptors of type formRelativePosition. */
  50. #define kAENext                        'next'
  51. #define kAEPrevious                    'prev'
  52.  
  53. /********** Keywords for getting fields out of object specifier records **********/
  54. #define keyAEDesiredClass            'want'
  55. #define keyAEContainer                'from'
  56. #define keyAEKeyForm                'form'
  57. #define keyAEKeyData                  'seld'
  58.  
  59.  
  60. /********** Keywords for getting fields out of Range specifier records **********/
  61. #define keyAERangeStart                'star'        /* These are the only two fields in the range desc */
  62. #define keyAERangeStop                'stop'
  63.     
  64. /********** Possible values for the keyAEKeyForm field of an object specifier **********/
  65. /* Remember that this set is an open-ended one.  The OSL makes assumptions about some of them,
  66.   but nothing in the grammar says you can't define your own */
  67. #define formAbsolutePosition         'indx'         /* e.g., 1st, -2nd ( 2nd from end) */
  68. #define formRelativePosition        'rele'         /* next, previous */
  69. #define formTest                    'test'         /* A logical or a comparison */
  70. #define formRange                    'rang'         /* Two arbitrary objects and everything in between */
  71. #define formPropertyID                'prop'         /* Key data is a 4-char property name */
  72. #define formName                    'name'         /* Key data may be of type 'TEXT' */
  73.  
  74. /************** Various relevant types ****************/
  75. /* Some of these tend to be paired with certain of the forms above.  Where this
  76.   is the case comments indicating the form(s) follow. */
  77. #define typeObjectSpecifier          'obj '        /* keyAEContainer will often be one of these */
  78. #define typeObjectBeingExamined     'exmn'        /* Another possible value for keyAEContainer */
  79. #define typeCurrentContainer        'ccnt'        /* Another possible value for keyAEContainer */
  80. #define typeToken                    'toke'        /* Substituted for 'ccnt' before accessor called */
  81.  
  82. #define typeRelativeDescriptor         'rel '        /* formRelativePosition */
  83. #define typeAbsoluteOrdinal         'abso'        /* formAbsolutePosition */
  84. #define typeIndexDescriptor            'inde'        /* formAbsolutePosition */
  85. #define typeRangeDescriptor          'rang'        /* formRange */
  86. #define typeLogicalDescriptor         'logi'        /* formTest is this or typeCompDescriptor */
  87. #define typeCompDescriptor            'cmpd'        /* formTest is this or typeLogicalDescriptor */
  88.     
  89. /************** various relevant keywords ****************/
  90. #define keyAECompOperator            'relo'        /* Relates two terms: '', '<', etc. */
  91. #define keyAELogicalTerms            'term'        /* An AEList of terms to be related by 'logc' below */
  92. #define keyAELogicalOperator        'logc'        /* kAEAND,  kAEOR or kAENOT */
  93. #define keyAEObject1                'obj1'        /* One of two objects in a term must be object specifier */
  94. #define keyAEObject2                'obj2'        /* The other object may be a simple descriptor or obj. spec. */
  95.  
  96.  
  97. /************ Special Handler selectors for OSL Callbacks ***************/
  98. /* You don't need to use these unless you are not using AESetObjectCallbacks. */
  99. #define keyDisposeTokenProc            'xtok'
  100. #define keyAECompareProc              'cmpr'
  101. #define keyAECountProc                  'cont'
  102. #define keyAEMarkTokenProc              'mkid'
  103. #define keyAEMarkProc                  'mark'
  104. #define keyAEAdjustMarksProc          'adjm'
  105. #define keyAEGetErrDescProc          'indc'
  106.  
  107. /************ Error codes ***************/
  108. /* OSL error codes: AEM proper uses up to -1719*/
  109. #define errAEImpossibleRange        -1720         /* A range like 3rd to 2nd, or 1st to all. */
  110. #define errAEWrongNumberArgs        -1721         /* Logical op kAENOT used with other than 1 term */
  111.  
  112. #define errAEAccessorNotFound         -1723         /* Accessor proc matching wantClass and containerType
  113.                                                 ...or wildcards not found */
  114. #define errAENoSuchLogical            -1725          /* Something other than AND, OR, or NOT */
  115. #define errAEBadTestKey                -1726         /* Test is neither typeLogicalDescriptor
  116.                                                 ...nor typeCompDescriptor */
  117. #define errAENotAnObjSpec            -1727          /* Param to AEResolve not of type 'obj ' */
  118. #define errAENoSuchObject            -1728          /* e.g.,: specifier asked for the 3rd, but there are only 2.
  119.                                                 ...Basically, this indicates a run-time resolution error. */
  120. #define errAENegativeCount            -1729         /* CountProc returned negative value */
  121. #define errAEEmptyListContainer        -1730         /* Attempt to pass empty list as container to accessor */
  122.     
  123. /* Possible values for flags parameter to AEResolve.  They're additive */
  124. #define kAEIDoMinimum                0x0000 
  125. #define kAEIDoWhose                    0x0001 
  126. #define kAEIDoMarking                0x0004 
  127.  
  128.  
  129. /* You only care about the constants that follow if you're doing your own whose
  130.   clause resolution */
  131. #define typeWhoseDescriptor            'whos'
  132. #define formWhose                    'whos'
  133. #define typeWhoseRange                'wrng'
  134. #define keyAEWhoseRangeStart        'wstr'
  135. #define keyAEWhoseRangeStop            'wstp'
  136. #define keyAEIndex                    'kidx'
  137. #define keyAETest                    'ktst'
  138.  
  139. struct ccntTokenRecord {        /* used for rewriting tokens in place of 'ccnt' descriptors        */
  140.         DescType tokenClass ;    /* This record is only of interest to those who, when they...    */
  141.         AEDesc token ;            /* ...get ranges as key data in their accessor procs, choose    */
  142.     } ;                            /* ...to resolve them manually rather than call AEResolve again.    */
  143.     
  144. typedef struct ccntTokenRecord ccntTokenRecord, *ccntTokenRecPtr, **ccntTokenRecHandle ;
  145.  
  146. typedef AEDesc *DescPtr, **DescHandle ;
  147.  
  148. /* typedefs providing type checking for procedure pointers */
  149.  
  150. typedef pascal OSErr (*accessorProcPtr) ( DescType desiredClass,
  151.         const AEDesc *container, DescType containerClass, DescType form,
  152.         const AEDesc *selectionData, AEDesc *value, long LongInt ) ;
  153.  
  154. typedef pascal OSErr (*compareProcPtr)( DescType oper, const AEDesc *obj1,
  155.             const AEDesc *obj2, Boolean *result ) ;
  156. typedef pascal OSErr (*countProcPtr)( DescType desiredType, DescType containerClass,
  157.             const AEDesc *container, long *result ) ;
  158. typedef pascal OSErr (*disposeTokenProcPtr)( AEDesc *unneededToken ) ;
  159.  
  160. typedef pascal OSErr (*getMarkTokenProcPtr)( const AEDesc *dContainerToken, DescType containerClass,
  161.             AEDesc *result ) ;
  162.  
  163.  
  164. typedef pascal OSErr (*getErrDescProcPtr)( DescPtr *appDescPtr ) ;
  165.  
  166. /* Note: app is supposed to dispose of dToken after marking */
  167. typedef pascal OSErr (*markProcPtr)( const AEDesc *dToken, const AEDesc *markToken, long index ) ;
  168. typedef pascal OSErr (*adjustMarksProcPtr)( long newStart, long newStop, const AEDesc *markToken ) ;
  169.  
  170.  
  171.  
  172. /*——————————————————————————————— PUBLIC PROCEDURES —————————————————————————————————*/
  173.  
  174.  
  175. pascal OSErr  AEObjectInit() ;
  176. /* Not done by inline, but by direct linking into code.  It sets up the pack
  177.   such that further calls can be via inline */
  178.  
  179. pascal OSErr AESetObjectCallbacks(
  180.                             compareProcPtr        myCompareProc,
  181.                             countProcPtr        myCountProc,
  182.                             disposeTokenProcPtr myDisposeTokenProc,    
  183.                             getMarkTokenProcPtr myGetMarkTokenProc,            /* called when mark (below) is true (all 3)*/
  184.                             markProcPtr            myMarkProc,
  185.                             adjustMarksProcPtr    myAdjustMarksProc,
  186.                             getErrDescProcPtr    myGetErrDescProcPtr )
  187. = { 0x303C, 0x0E35, 0xA816 } ;
  188.  
  189.  
  190.  
  191.  
  192. pascal OSErr  AEResolve        (    const AEDesc    *objectSpecifier,
  193.                                 short            callbackFlags,        /* see above for possible values */
  194.                                   AEDesc            *theToken )
  195. = { 0x303C, 0x0536, 0xA816 } ;
  196.  
  197.  
  198. pascal OSErr AEInstallObjectAccessor(
  199.                                 DescType        desiredClass,
  200.                                    DescType        containerType,
  201.                                    accessorProcPtr theAccessor,
  202.                                    long            accessorRefcon,
  203.                                    Boolean            isSysHandler )
  204. = { 0x303C, 0x0937, 0xA816 } ;
  205.  
  206. pascal OSErr AERemoveObjectAccessor(
  207.                                 DescType        desiredClass,
  208.                                 DescType        containerType,
  209.                                 accessorProcPtr theAccessor,
  210.                                 Boolean            isSysHandler )
  211. = { 0x303C, 0x0738, 0xA816 } ;
  212.  
  213. pascal OSErr AEGetObjectAccessor(
  214.                                 DescType         desiredClass,
  215.                                 DescType        containerType,
  216.                                 accessorProcPtr    *accessor,
  217.                                 long            *accessorRefcon,
  218.                                 Boolean            isSysHandler )
  219. = { 0x303C, 0x0939, 0xA816 } ;
  220.  
  221. pascal OSErr AEDisposeToken( AEDesc *theToken )
  222. = { 0x303C, 0x023A, 0xA816 } ;
  223.  
  224. pascal OSErr AECallObjectAccessor(    DescType        desiredClass,
  225.                                     const AEDesc    *containerToken,
  226.                                     DescType        containerClass,
  227.                                     DescType        keyForm,
  228.                                     const AEDesc    *keyData,
  229.                                     AEDesc            *token )
  230. = { 0x303C, 0x0C3B, 0xA816 } ;
  231.  
  232.  
  233.  
  234.  
  235. /*
  236. Here are the interfaces your callback procs must be written to:
  237.  
  238. pascal OSErr MyCompareProc( DescType comparisonOperator, const AEDesc *theObject,
  239.         const AEDesc *descOrObj, Boolean *result ) ;
  240. pascal OSErr MyCountProc( DescType desiredType, DescType containerClass,
  241.             const AEDesc *container, long *result:  ) ;
  242. pascal OSErr MyGetMarkToken( const AEDesc *containerToken, DescType containerClass,
  243.         AEDesc *result ) ;
  244. pascal OSErr MyMark( const AEDesc *theToken, const AEDesc *markToken, long markCount ) ;
  245. pascal OSErr MyAdjustMarks( long newStart, long newStop, const AEDesc *markToken ) ;
  246. pascal OSErr MyMyDisposeToken( AEDesc *unneededToken ) ;
  247. pascal OSErr MyGetErrDesc( DescPtr *appDescPtr ) ;
  248.  
  249. pascal OSErr MyObjectAccessor( DescType desiredClass, const AEDesc *containerToken,
  250.         DescType containerClass, DescType keyForm, const AEDesc *keyData,
  251.         AEDesc *theToken, long *theRefcon ) ;
  252.  
  253. You'll probably want to have a number of these last ones.
  254. A proc that finds a line within a document should be installed with 'line' and 'docu'
  255. as the desiredClass and containerClass fields in the call to AEInstallObjectHandler().
  256. */
  257.  
  258. #endif
  259.